feat: high-resolution timer wheel for scheduled Soroban executions (#56)#91
Merged
elizabetheonoja-art merged 1 commit intoJun 26, 2026
Conversation
…tility-Protocol#56) Schedules up to 1,000 recurring contract executions with ms precision that keeps firing while the tab is throttled, via a Web Worker ticking on a SharedArrayBuffer. - types/scheduler.ts: wheel invariants (1024 slots x 100ms, 1000-job cap, +/-50ms tolerance, 200ms fallback), job/meta/status types, SAB Int32 layout, worker protocol - utils/sharedBuffer.ts: SharedArrayBuffer creation + atomic drift/heartbeat/ command helpers, availability check (COOP/COEP), futexWait/notify with non-shared fallback - utils/timerWheelCore.ts: pure hashed wheel (rounds + pending set so sub-slot jobs are never skipped); schedule/cancel/advance with recurrence, drift correction, missed-fire detection, and the 1000-job cap - workers/timerWheel.worker.ts: holds the wheel, sleeps each tick on Atomics.wait(HEARTBEAT, 100ms) (timed-loop fallback), advances and posts fired jobs; command channel via postMessage + Atomics.notify - services/timerWheel.ts: main-thread facade — worker path or 200ms polling fallback, requestAnimationFrame drift loop writing correction while hidden - hooks/useScheduledExecution.ts: wraps the service, mirrors metadata to the store, auto-cancels on unmount - store/slices/scheduleSlice.ts: job metadata (next fire, status, missed count) - components/dashboard/SchedulerDashboard.tsx: jobs table + cancel (component rather than src/pages since this is an App Router project) - tests for the wheel (ordering, rounds, recurrence, cancel, cap, precision, drift), the atomic buffer helpers, and the schedule store
elizabetheonoja-art
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
High-Resolution Timer Wheel for Scheduled Soroban Executions (#56)
Closes #56
What's included
src/types/scheduler.tssrc/utils/sharedBuffer.tsfutexWait/futexNotifythat degrade safely on a non-shared buffer.src/utils/timerWheelCore.tsroundscounter for >1-rotation targets, and apendingset so sub-slot jobs are never skipped.schedule/cancel/advancewith recurrence, drift correction, missed-fire detection, and the 1,000-job cap.src/workers/timerWheel.worker.tsAtomics.wait(HEARTBEAT, …, 100ms)(woken early by command notifies; timed-loop fallback without SAB), advances usingDate.now(), and posts fired jobs.src/services/timerWheel.tsrequestAnimationFrameloop that writes a drift correction into the buffer while the tab is hidden.src/hooks/useScheduledExecution.tssrc/store/slices/scheduleSlice.tssrc/components/dashboard/SchedulerDashboard.tsxtests/unit/*